<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>FileRead</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link href="../css/default.css" rel="stylesheet" type="text/css">
</head>
<body>

<h1>FileRead</h1>

<p>读取文件的内容到 <a href="../Variables.htm">变量</a> 中.</p>

<pre class="Syntax">FileRead, OutputVar, Filename</pre>
<h3>参数</h3>
<table class="info">
  <tr> 
    <td>OutputVar</td>
    <td>用于保存获取的数据的 <a href="../Variables.htm">变量</a> 名称. 如果遇到问题例如文件 "在使用中" 或不存在则 <em>OutputVar</em> 被置空 (此时 <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 被设置为 1). 如果 <em>Filename</em> 是个空文件输出变量也被置空 (此时 ErrorLevel 被设置为 0).</td>
  </tr>
  <tr> 
    <td width="15%">Filename</td>
    <td width="85%"><p>需读取的文件的名称, 如果没有指定绝对路径则假定在 <a href="../Variables.htm#WorkingDir">A_WorkingDir</a> 中.</p>
      <p><strong>选项</strong>: 零个或多个下列字符串还可以直接放在文件名的前面. 在选项间使用单个空格或 Tab 分隔. 例如: *t *m5000 C:\Log Files\200601.txt</p>
    <p><strong>*c</strong>: 读取保存了 <a href="../misc/Clipboard.htm#ClipboardAll">ClipboardAll</a> 内容的文件. 使用了 <strong>*c</strong> 选项时其他所有选项被忽略.</p>
    <p><strong>*m1024</strong> <span class="ver">[v1.0.43.03+]:</span> 如果省略此选项, 则读取整个文件除非它大于 1 GB, 此时根本不读取文件. 否则, 使用 1 到 1073741824 (1 GB) 字节的十进制或十六进制数代替 1024. 如果文件大于此字节数, 那么只读取其前面部分. 注意: 此选项可能导致最后一行以单独的回车符 (`r) 而不是 `r`n 结束.</p>    
    <p><strong>*t</strong>: 用换行符 (`n) 替换所有的回车换行符 (`r`n). 不过, 这种转换降低性能而且往往不必要. 例如, 包含 `r`n 的文本已经是添加到 <a href="StringReplace.htm">Gui  编辑控件</a> 的正确格式. 同样地, <a href="FileAppend.htm">FileAppend</a> 打开新文件时会检测是否含有 `r`n; 它知道按现在的样子写入每对 `r`n 而不是把它转换成 `r`r`n. 最后, 不论每行的结束符是 `r`n 或只是 `n, 后面的 <a href="LoopParse.htm">解析循环</a> 都可以正确执行: <em>Loop, parse, MyFileContents, `n, `r</em></p>
    <p><strong>*Pnnn</strong>: <span class="ver">[AHK_L 42+]:</span> 覆盖 <a href="FileEncoding.htm">FileEncoding</a> 包含的默认编码设置, 这里 <em>nnn</em> 必须是数值的 <a href="http://msdn.microsoft.com/en-us/library/dd317756.aspx">代码页标识符</a>.</td>
  </tr>
</table>

<h3>返回值</h3>
<p>如果读取成功 <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 被设置为 0. 如果遇到问题它被设置为 1, 例如: 1) 文件不存在; 2) 文件被锁定或无法访问; 3) 系统没有足够的内存加载文件.</p>
<p><a href="../Variables.htm#LastError">A_LastError</a> 被设置为操作系统 GetLastError() 函数返回的结果.</p>

<h3 id="Binary">读取二进制数据 <span class="ver">[AHK_L 42+]</span></h3>
<p>根据文件, 参数和默认设置, FileRead 可能把文件数据解释为文本并且把它转换成脚本使用的 <a href="../Compat.htm#Format">原生编码</a>. 如果文件包含二进制数据这样操作很可能引起问题, 除非在下列情况下:</p>
<ul>
  <li>如果存在 <span class="Syntax">*C</span> 选项, 所有代码页和行结束符的转换都无条件忽略.</li>
  <li>如果存在 <span class="Syntax">*P<i>nnn</i></span> 选项并且 <i>nnn</i> 符合原生字符串编码, 不会进行代码页转换.</li>
  <li>如果当前 <a href="commands/FileEncoding.htm">文件编码</a> 设置符合原生字符串编码, 不会进行代码页转换.</li>
</ul>
<p>此外, 可以使用 <a href="FileOpen.htm">FileOpen()</a> 和 <a href="../objects/File.htm#RawRead">File.RawRead()</a> 读取二进制数据.</p>

<h3>备注</h3>
<p>当需要读取文件的全部或大部分内容到内存时, 使用 FileRead 比 <a href="LoopReadFile.htm">文件读取循环</a> 执行的更好.</p>
<p>大于 1 GB 的文件将导致 <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 被设置为 1 并且 <em>OutputVar</em> 被置空除非使用了 <strong>*m</strong> 选项, 此时读取文件的前面部分.</p>
<p>FileRead 不服从 <a href="_MaxMem.htm">#MaxMem</a> 的设置. 如果担心使用太多内存, 预先用 <a href="FileGetSize.htm">FileGetSize</a> 检查文件的大小.</p>
<p>如果指定的文件包含二进制零 (它决不可能出现在正确的文本文件中), 那么仅仅在首个二进制零前面的文本会被 AutoHotkey 命令和函数 "看到". 但是, 整个文件的内容仍会保存到 <em>OutputVar</em> 中并且可以通过高级的方法例如 <a href="../Functions.htm#NumGet">NumGet()</a> 和 <a href="../Variables.htm#amp">地址运算符 (&amp;)</a> 访问; 例如: *(&amp;OutputVar + 1000)</p>
<p>与 <a href="LoopReadFile.htm">文件读取循环</a> 和 <a href="FileReadLine.htm">FileReadLine</a> 不同, FileRead 不会把 控制字符 Control-Z (0x1A) 作为文件结束的标记. 因此任何的 Control-Z, 即使出现在文件的最后, 也会被照常读取.</p>
<p>使用 FileRead 可以快速对文件的内容进行排序, 如下所示:</p>
<pre>FileRead, Contents, C:\Address List.txt
if not ErrorLevel  <em>; 成功读取.</em>
{
    <a href="Sort.htm">Sort</a>, Contents
    FileDelete, C:\Address List (alphabetical).txt
    FileAppend, %Contents%, C:\Address List (alphabetical).txt
    Contents =  <em>; 清空占用的内存.</em>
}</pre>
<p><span class="ver">[AHK_L 42+]:</span> <a href="FileOpen.htm">FileOpen()</a> 比 FileRead 提供了更高级的功能, 例如在文件中指定的位置读取或写入数据而不需要读取整个文件到内存中. 参见 <a href="../objects/File.htm">文件对象</a> 了解函数列表.</p>

<h3>相关</h3>
<p><a href="FileOpen.htm">FileOpen</a>/<a href="../objects/File.htm">文件对象</a>, <a href="LoopReadFile.htm">文件读取循环</a>, <a href="FileReadLine.htm">FileReadLine</a>, <a href="FileGetSize.htm">FileGetSize</a>, <a href="FileAppend.htm">FileAppend</a>, <a href="IniRead.htm">IniRead</a>, <a href="Sort.htm">Sort</a>, <a href="UrlDownloadToFile.htm">UrlDownloadToFile</a></p>

<h3>示例</h3>
<pre class="NoIndent">FileRead, OutputVar, C:\My Documents\My File.txt</pre>

</body>
</html>
